Updating from v12 to v13

v13 requires Node 16.6 or higher to use, so make sure you're up to date. To check your Node version, use node -v in your terminal or command prompt, and if it's not high enough, update it! There are many resources online to help you with this step based on your host system.

Once you've got Node up-to-date, you can install v13 by running the appropriate command in your terminal or command prompt.

You can check your discord.js version with the list command. Should it still show v12.x, uninstall and re-install discord.js and make sure the entry in your package.json does not prevent a major version update. Please refer to the npm documentationopen in new window for this.

discord.js v13 makes the switch to Discord API v9! In addition to this, the new major version also includes a bunch of cool new features.

discord.js now has support for slash commands! Refer to the slash commands section of this guide to get started.

In addition to the interactionCreate event covered in the above guide, this release also includes the new Client events applicationCommandCreate, applicationCommandDelete, and applicationCommandUpdate.

discord.js now has support for message components! This introduces the MessageActionRow, MessageButton, and MessageSelectMenu classes, as well as associated interactions and collectors.

Refer to the message components section of this guide to get started.

discord.js now has support for threads! Threads are a new type of sub-channel that can be used to help separate conversations into a more meaningful flow.

This introduces the ThreadManager class, which can be found as TextChannel#threads, in addition to ThreadChannel, ThreadMemberManager, and ThreadMember. There are also five new events: threadCreate, threadUpdate, threadDelete, threadListSync, threadMemberUpdate, and threadMembersUpdate.

Refer to the threads section of this guide to get started.

Support for voice has been separated into its own module. You now need to install and use @discordjs/voiceopen in new window for interacting with the Discord Voice API.

Refer to the voice section of this guide to get started.

A popular request that has finally been heard - the Client class now has a new option, makeCache. It accepts a CacheFactory.

By combining this with the helper function Options.cacheWithLimits, users can define limits on each Manager's cache and let discord.js handle the rest.

Additional flexibility can be gained by providing a function which returns a custom cache implementation. Keep in mind this should still maintain the Collection/Map-like interface for internal compatibility.

With the introduction of Interactions and it becoming far common for users to want to send an embed with MessageOptions, methods that send messages now enforce a single param. This can be either a string, a MessagePayload, or that method's variant of MessageOptions.

Additionally, all messages sent by bots now support up to 10 embeds. As a result, the embed option was removed and replaced with an embeds array, which must be in the options object.

MessageEmbed#attachFiles has been removed; files should now be attached directly to the message instead of the embed.

The code and split options have also been removed. This functionality will now have to be handled manually, such as via the Formatters.codeBlock and Util.splitMessage helpers.

Many methods in discord.js that were documented as accepting strings would also accept other types and resolve this into a string on your behalf. The results of this behavior were often undesirable, producing output such as [object Object].

discord.js now enforces and validates string input on all methods that expect it. Users will need to manually call toString() or utilize template literals for all string inputs as appropriate.

The most common areas you will encounter this change in are: MessageOptions#content, the properties of a MessageEmbed, and passing objects such as users or roles, expecting them to be stringified.

As v13 makes the switch to Discord API v9, it is now required to specify all intents your bot uses in the Client constructor. The intents option has also moved from ClientOptions#ws#intents to ClientOptions#intents.

The shortcuts Intents.ALL, Intents.NON_PRIVILEGED, and Intents.PRIVILEGED have all been removed to discourage bad practices of enabling unused intents.

Refer to our more detailed article about this topic.

The concept of extendable Structures has been completely removed from discord.js. For more information on why this decision was made, refer to this pull requestopen in new window.

There is no swap-in replacement for this, as the intention is to change the code design rather than enable something equally bad.

For some real-world example of the alternatives provided in the PR, you may have been extending the Guild class with guild-specific settings:

This functionality can be replicated using the WeakMap or Collection example, even attaching it to the Client if necessary:

All Collector related classes and methods (both .create*() and .await*()) now take a single object parameter which also includes the filter.

Some commonly used naming conventions in discord.js have changed.

The casing of thingID properties has changed to thingId. This is a more-correct casing for the camelCase used by discord.js as Id is an abbreviation of Identifier, not an acronym.

This includes: afkChannelId, applicationId, channelId, creatorId, guildId, lastMessageId, ownerId, parentId, partyId, processId, publicUpdatesChannelId, resolveId, rulesChannelId, sessionId, shardId, systemChannelId, webhookId, widgetChannelId, and workerId.

The message event has been renamed to messageCreate, to bring the library in line with Discord's naming conventions. Using message will still work, but you'll receive a deprecation warning until you switch over.

clientOptions.disableMentions has been removed and replaced with clientOptions.allowedMentions! The Discord API now allows bots much more granular control over mention parsing, down to the specific id.

Refer to the Discord API documentationopen in new window for more information.

Message#reply will no longer result in the bot prepending a user mention to the content, replacing the behavior with Discord's reply feature.

MessageOptions#reply no longer takes a user id. It has been replaced with a ReplyOptions type, expecting MessageOptions#reply#messageReference as a Message id.

The new MessageOptions.allowedMentions.repliedUser boolean option determines if the reply will notify the author of the original message.

Note that this will disable all other mentions in this message. To enable other mentions, you will need to include other allowedMentions fields. See the above "Allowed Mentions" section for more.

Bitfields are now BigInts instead of Numbers. This can be handled using the BigInt() class, or the n-suffixed BigInt literalopen in new window.

In addition, the usage of string literals for bitfield flags such as Permissions and UserFlags is discouraged; you should use the flag instead.

On Discord API v8 and later, DM Channels do not emit the CHANNEL_CREATE event, which means discord.js is unable to cache them automatically. In order for your bot to receive DMs, the CHANNEL partial must be enabled.

Webpack builds are no longer supported.

The CUSTOM_STATUS type has been renamed to CUSTOM.

The APIMessage class has been renamed to MessagePayload, resolving a naming clash with an interface in the discord-api-types library which represents raw message data objects.

Channel types are now uppercase and align with Discord's naming conventions.

The Client Emoji manager is now a BaseGuildEmojiManager, providing cache resolution only and removing methods that would fail to create emojis as there was no Guild context.

The Client#fetchApplication method has been removed and replaced with the Client#application property.

This method has been renamed to fetchGuildWidget to better represent its functionality.

Client#generateInvite no longer supports PermissionsResolvable as its argument, requiring InviteGenerationOptions instead. This also requires that at least one of either bot or applications.commands is provided in scopes to generate a valid invite URL.

To generate an invite link with slash commands permissions:

To generate an invite link for a bot and define required permissions:

Previously when a token had reached its 1000 login limit for the day, discord.js would treat this as a rate limit and silently wait to login again, but this was not communicated to the user. This will now instead cause an error to be thrown.

The Client#typingStart event now only emits a Typing structure. Previously, Channel and User were emitted.

The Client timeout methods have all been removed. These methods existed for the purpose of caching timeouts internally so they could be cleared when the Client is destroyed. Since timers now have an unref method in Node, this is no longer required.

The ClientOptions#fetchAllMembers option has been removed.

With the introduction of gateway intents, the fetchAllMembers Client option would often fail and causes significant delays in ready states or even cause timeout errors. As its purpose is contradictory to Discord's intentions to reduce scraping of user and presence data, it has been removed.

The ClientOptions#messageCacheMaxSize option has been removed. Instead, use ClientOptions#makeCache to customize the MessageManager cache.

The ClientOptions#messageEditHistoryMaxSize option has been removed.

To reduce caching, discord.js will no longer store an edit history. You will need to implement this yourself if required.

The ClientUser#setActivity method no longer returns a Promise.

The ClientUser#setAFK method no longer returns a Promise.

The ClientUser#setPresence method no longer returns a Promise.

PresenceData#activity was replaced with PresenceData#activities, which now requires an Array.

The ClientUser#setStatus method no longer returns a Promise.

These methods existed to provide access to a cached array of Collection values and keys respectively, which other Collection methods relied on internally. Those other methods have been refactored to no longer rely on cache, so those arrays and these methods have been removed.

You should instead construct an array by spreading the iterators returned by the base Map class methods:

Colors have been updated to align with the new Discord branding.

This method has been removed, with functionality replaced by the new GuildMemberManager#add.

These methods have been removed, with functionality replaced by the new GuildBanManager.

This method has been removed, with functionality replaced by the new GuildInviteManager.

The Guild#fetchVanityCode method has been removed.

The Guild#fetchWidget() method now retrieves the widget data for the guild instead of the widget settings. See Client#fetchGuildWidget(). The original functionality has moved to the new method Guild#fetchWidgetSettings().

The Guild#member() helper/shortcut method has been removed.

The Guild#mfaLevel property is now an enum.

The Guild#nsfw property has been removed, replaced by Guild#nsfwLevel.

The Guild#owner property has been removed as it was unreliable due to caching, replaced with Guild#fetchOwner.

The Guild#setWidget() method has been renamed to Guild#setWidgetSettings().

The Guild#voice getter has been removed.

This method has been removed, with functionality replaced by the new PermissionOverwriteManager.

These methods have been removed from GuildChannel and placed only on subclasses for which invites can be created. These are TextChannel, NewsChannel, VoiceChannel, StageChannel, and StoreChannel.

On these subclasses, the method now supports additional options:

This method has been removed, with functionality replaced by the new PermissionOverwriteManager.

This method no longer returns a Collection of PermissionOverwrites, instead providing access to the PermissionOverwriteManager.

The GuildChannel#setTopic method has been removed and placed only on subclasses for which topics can be set. These are TextChannel, NewsChannel, and StageChannel.

This method has been removed, with functionality replaced by the new PermissionOverwriteManager.

GuildMember#ban() will throw a TypeError when a string is provided instead of an options object.

The GuildMember#hasPermission shortcut/helper method has been removed.

None of these properties were actually provided by Discord, instead relying on potentially inaccurate client cache, and have been removed.

The GuildMember#presence property can now be null, rather than a generic offline presence, such as when the GUILD_PRESENCES intent is not enabled.

The GuildMemberManager#ban method will throw a TypeError when a string is provided instead of an options object.

The Message.delete() method no longer accepts any options, requiring a timed-delete to be performed manually.

reason is no longer a parameter as it is not used by the API.

The MessageManager.delete() method no longer accepts any additional options, requiring a timed-delete to be performed manually.

reason is no longer a parameter as it is not used by the API.

The Message#edits property has been removed.

The MessageEmbed#attachFiles method has been removed. Instead, files should be attached to the Message directly via MessageOptions.

Permissions.FLAGS.MANAGE_EMOJIS is now Permissions.FLAGS.MANAGE_EMOJIS_AND_STICKERS.

The before option has been removed as it was not supported by the API.

The options passed to RoleManager#create no longer need to be nested in a data object. Additionally, reason is now part of the options, not a second parameter.

The RoleManager#fetch() method will now return a Collection instead of a RoleManager when called without params.

The options for the Shard#respawn method are now an object instead of separate params. In addition, the spawnTimeout param has been renamed to timeout. This means the user no longer needs to pass defaults to fill each positional param.

The spawnTimeout param has been renamed to timeout.

The ShardClientUtil#broadcastEval method no longer accepts a string, instead expecting a function.

The options for the ShardClientUtil#respawnAll method are now an object instead of separate params. In addition, the spawnTimeout param has been renamed to timeout. This means the user no longer needs to pass defaults to fill each positional param.

The ShardingManager#broadcastEval method no longer accepts a string, instead expecting a function. See ShardClientUtil#broadcastEval.

The options for the ShardingManager#spawn method are now an object instead of separate params. In addition, the spawnTimeout param has been renamed to timeout. This means the user no longer needs to pass defaults to fill each positional param.

The options for the ShardingManager#respawnAll method are now an object instead of separate params. In addition, the spawnTimeout param has been renamed to timeout. This means the user no longer needs to pass defaults to fill each positional param.

These methods have both been replaced by a singular TextChannel.sendTyping(). This method automatically stops typing after 10 seconds, or when a message is sent.

Neither of these properties were actually provided by Discord, instead relying on potentially inaccurate client cache, and have been removed.

The User.locale property has been removed, as this property is not exposed to bots.

The User.presence property has been removed. Presences are now only found on GuildMember.

As discord.js no longer caches typing event data, the User.typingIn() method has been removed.

As discord.js no longer caches typing event data, the User.typingSinceIn() method has been removed.

As discord.js no longer caches typing event data, the User.typingDurationIn() method has been removed.

The deprecated UserFlags DISCORD_PARTNER and VERIFIED_DEVELOPER / EARLY_VERIFIED_DEVELOPER have been removed in favor of their renamed versions.

The new flag DISCORD_CERTIFIED_MODERATOR has been added.

Shortcuts to Util methods which were previously exported at the top level have been removed.

Both were removed in favor of Node's built-in Buffer methods.

The Util#fetchRecommendedShards() method now supports an additional option multipleOf to calculate the number to round up to, e.g. a multiple of 16 for large bot sharding.

The Util#resolveString method has been removed. discord.js now enforces that users provide strings where expected rather than resolving one on their behalf.

The VoiceState#kick method has been renamed to VoiceState#disconnect.

The WebhookClient constructor no longer accepts id, token as the first two parameters, instead taking a data object. This object supports an additional option url, allowing creation of a WebhookClient from a webhook URL.

A new activity type COMPETING has been added.

Provides API support for slash commands.

Provides API support for creating, editing and deleting slash commands.

Provides API support for creating, editing, and deleting permission overwrites on slash commands.

Provides an enumerated bitfield for ClientApplication flags.

The new BaseGuild class is extended by both Guild and OAuth2Guild.

The new BaseGuildTextChannel class is extended by both TextChannel and NewsChannel.

The new BaseGuildVoiceChannel class is extended by both VoiceChannel and StageChannel.

Provides gateway support for a MessageComponentInteraction coming from a button component.

Checks and typeguards if a channel is Text-Based; one of TextChannel, DMChannel, NewsChannel or ThreadChannel.

Checks and typeguards if a channel is a ThreadChannel.

Checks and typeguards if a channel is Voice-Based; VoiceChannel or StageChannel.

Emitted when a guild application command is created.

Emitted when a guild application command is deleted.

Emitted when a guild application command is updated.

Emitted when an interaction is created.

Emitted when a stage instance is created.

Emitted when a stage instance is deleted.

Emitted when a stage instance gets updated, e.g. change in topic or privacy level.

Emitted when a custom sticker is created in a guild.

Emitted when a custom sticker is deleted in a guild.

Emitted when a custom sticker is updated in a guild.

Emitted when a thread is created or when the client user is added to a thread.

Emitted when a thread is deleted.

Emitted when the client user gains access to a text or news channel that contains threads.

Emitted when members are added or removed from a thread. Requires the GUILD_MEMBERS privileged intent.

Emitted when the client user's thread member is updated.

Emitted when a thread is updated, e.g. name change, archive state change, locked state change.

This parameter sets the default behavior for ReplyMessageOptions#failIfNotExists, allowing or preventing an error when replying to an unknown Message.

This parameter is now optional and will fall back to a function that always returns true if not provided.

Provides gateway support for slash command interactions. For more information refer to the slash commands section of the guide.

Provides access to the Guild's GuildBanManager.

Guild#systemChannelFlags can now be set in the Guild#create method.

The Guild#description and Guild#features properties can now be edited.

Provides API support for bots to edit the Guild's WelcomeScreen.

The GuildEmojiManager class now extends BaseGuildEmojiManager. In addition to the existing methods, it now supports GuildEmojiManager#fetch.

Provides API support for fetching the Guild's WelcomeScreen.

Provides API support for the Guild's Widget, containing information about the guild and its members.

Provides access to the new GuildInviteManager.

The Guild#nsfwLevel property is now represented by the NSFWLevel enum.

The Guild#premiumTier property is now represented by the PremiumTier enum.

Now supports setting the parent of multiple channels, and locking their permissions via the ChannelPosition#parent and ChannelPosition#lockPermissions options.

Provides improved API support for handling and caching bans.

Starting from 13.11, developers should utilise deleteMessageSeconds instead of days:

days is deprecated and will be removed in the future.

Now supports setting the position property.

Now supports fetching the channels of a Guild.

Retrieves a list of the active threads in a Guild.

Aligns support for creating and fetching invites with the managers design. This replaces Guild#fetchInvites.

Now supports specifying the AFK and system channels when creating a new guild.

Now supports fetching multiple guilds, returning a Promise if used in this way.

Provides API support for the GET /guilds/{guild.id}/emojis endpoint.

Flags whether a member has passed the guild's membership gate. The flag is true before accepting and fires guildMemberUpdate when the member accepts.

Several methods were added to GuildMemberManager to provide API support for uncached members.

guild.members.edit('123456789012345678', data, reason) is equivalent to GuildMember#edit(data, reason).

guild.members.kick('123456789012345678', reason) is equivalent to GuildMember#kick(reason).

Provides API support for querying GuildMembers via the REST API endpoint. GuildMemberManager#fetch uses the websocket gateway to receive data.

Gets the managed role this member created when joining the guild if any.

Gets the premium subscriber (booster) role if present on the member.

The datetime at which the GuildPreview was created.

Provides API support for server templatesopen in new window.

A Collection of Roles which are managed by the integration.

Provides gateway support for slash command and message component interactions.

For more information refer to the slash commands and message components sections of the guide.

Provides a way for users to collect any type of Interaction. This class has a more flexible design than other Collectors, able to be bound to any Guild, Channel, or Message as appropriate. TypeScript developers can also leverage generics to define the subclass of Interaction that will be returned.

Provides webhook support specifically for interactions, due to their unique qualities.

Provides API support for the partial Guild data available from an Invite.

Provides API support for bots to inviting users to stage instances.

A shortcut method to create a promisified InteractionCollector which resolves to a single MessageComponentInteraction.

A shortcut method to create an InteractionCollector for components on a specific message.

Checks permissions to see if a Message can be crossposted.

Editing and/or removing attachments when editing a Message is now supported.

Provides support for fetching the Message referenced by Message#reference, if the client has access to do so.

Now supports both and as valid inputs.

Removes the attachments from a message. Requires MANAGE_MESSAGES to remove attachments from messages authored by other users.

Starts a ThreadChannel using this message as the starter message.

A Collection of Stickers in the message.

A builder class which makes constructing action row type message components easier.

The media type of a MessageAttachment.

A builder class which makes constructing button type message components easier.

Provides gateway support for receiving interactions from message components. Subclass of Interaction.

Replaces all fields in the embed with the new array of fields provided.

embed.setFields(newFields) is equivalent to embed.spliceFields(0, embed.fields.length, newFields).

Methods were added to MessageManager to provide API support for uncached messages.

channel.messages.crosspost('876543210987654321') is equivalent to message.crosspost().

channel.messages.edit('876543210987654321', content, options) is equivalent to message.edit(content, options).

channel.messages.pin('876543210987654321', options) is approximately equivalent to message.pin(options) but does not resolve to a Message.

channel.messages.react('876543210987654321', emoji) is approximately equivalent to message.react(emoji) but does not resolve to a MessageReaction.

channel.messages.unpin('876543210987654321', options) is approximately equivalent to message.unpin(options) but does not resolve to a Message.

Checks if the author of a message being replied to has been mentioned.

This class has been renamed from APIMessage. Global headers can now be set in the HTTP options.

A builder class which makes constructing select menu type message components easier.

Provides API support for bots to follow announcements in other channels.

Allows conversion between NewsChannel and TextChannel.

Static bitfield representing the permissions required to moderate a stage channel.

Replaces the createOverwrite, updateOverwrite, and overwritePermissions methods of GuildChannel, aligning the design with other Managers.

Tags for roles belonging to bots, integrations, or premium subscribers.

Gets the managed role a bot created when joining the guild, if any.

guild.roles.edit('123456789098765432', options) is equivalent to role.edit(options).

Gets the premium subscriber (booster) role for the Guild, if any.

Provides gateway support for a MessageComponentInteraction coming from a select menu component.

Provides API support for stage channels.

Provides API support for stage instances. Stage instances contain information about live stages.

Provides API support for the bot to create, edit, and delete live stage instances, and stores a cache of stage instances.

Provides API support for Discord Stickers.

Provides API support for Discord Sticker packs.

A shortcut method to create a promisified InteractionCollector which resolves to a single MessageComponentInteraction.

A shortcut method to create an InteractionCollector for components on a specific channel.

Allows conversion between TextChannel and NewsChannel.

Provides access to the ThreadManager for this channel.

Provides API support for thread channels.

Provides API support for the bot to create, edit, and delete threads, and stores a cache of ThreadChannels.

Represent a member of a thread and their thread-specific metadata.

Provides API support for the bot to add and remove members from threads, and stores a cache of ThreadMembers.

Represents a typing state for a user in a channel.

Webhooks can now delete messages that were sent by the Webhook.

Webhooks can now edit messages that were sent by the Webhook.

Webhooks can now fetch messages that were sent by the Webhook.

Webhooks can now have a sourceGuild and sourceChannel if the message is being crossposted.

Represents the channels that can be seen in a Guild's WelcomeScreen.

Provides API support for a Guild's welcome screen.

Represents a Guild's widget.

Partial information about a guild's members stored in a widget.

A number of new formatter functions are provided in the Util class, to easily handle adding markdown to strings.

A helper method that attempts to resolve properties for a raw emoji object from input data, without the use of the discord.js Client class or its EmojiManager.

A helper method which is used to internally validate string arguments provided to methods in discord.js.